6 The Format Description

The variable forms-format-list specifies the format of the data in the data file, and how to convert the data for display in Forms mode. Its value must be a list of Forms mode formatting elements, each of which can be a string, a number, a Lisp list, or a Lisp symbol that evaluates to one of those. The formatting elements are processed in the order they appear in the list.

string

A string formatting element is inserted in the forms “as is,” as text that the user cannot alter.

number

A number element selects a field of the record. The contents of this field are inserted in the display at this point. Field numbers count starting from 1 (one).

list

A formatting element that is a list specifies a function call. This function is called every time a record is displayed, and its result, which must be a string, is inserted in the display text. The function should do nothing but returning a string.

The function you call can access the fields of the record as a list in the variable forms-fields.

symbol

A symbol used as a formatting element should evaluate to a string, number, or list; the value is interpreted as a formatting element, as described above.

If a record does not contain the number of fields as specified in forms-number-of-fields, a warning message will be printed. Excess fields are ignored, missing fields are set to empty.

The control file which displays /etc/passwd file as demonstrated in the beginning of this manual might look as follows:

     ;; This demo visits /etc/passwd.

     (setq forms-file "/etc/passwd")
     (setq forms-number-of-fields 7)
     (setq forms-read-only t)                 ; to make sure
     (setq forms-field-sep ":")
     ;; Don't allow multi-line fields.
     (setq forms-multi-line nil)

     (setq forms-format-list
           (list
            "====== /etc/passwd ======\n\n"
            "User : "    1
            "   Uid: "   3
            "   Gid: "   4
            "\n\n"
            "Name : "    5
            "\n\n"
            "Home : "    6
            "\n\n"
            "Shell: "    7
            "\n"))

When you construct the value of forms-format-list, you should usually either quote the whole value, like this,

     (setq forms-format-list
          '(
            "====== " forms-file " ======\n\n"
            "User : "    1
            (make-string 20 ?-)
            ...
           ))

or quote the elements which are lists, like this:

     (setq forms-format-list
           (list
            "====== " forms-file " ======\n\n"
            "User : "    1
            '(make-string 20 ?-)
            ...
           ))

Forms mode validates the contents of forms-format-list when you visit a database. If there are errors, processing is aborted with an error message which includes a descriptive text. See Error Messages, for a detailed list of error messages.

If no forms-format-list is specified, Forms mode will supply a default format list. This list contains the name of the file being visited, and a simple label for each field indicating the field number.